From bfd0c1279810e2f4b0efe4312d2856d67162b528 Mon Sep 17 00:00:00 2001
From: Owen Taylor <otaylor@redhat.com>
Date: Tue, 26 Oct 1999 20:59:31 +0000
Subject: [PATCH] Added information about widget paths and pattern matching.

Tue Oct 26 16:50:15 1999  Owen Taylor  <otaylor@redhat.com>

	* gtk/tmpl/gtkrc.sgml: Added information about widget
	paths and pattern matching.
---
 docs/reference/ChangeLog           |  5 +++
 docs/reference/gtk/tmpl/gtkrc.sgml | 65 ++++++++++++++++++++++++++++--
 2 files changed, 66 insertions(+), 4 deletions(-)

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index a474648f9b..49f23e7ef1 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+Tue Oct 26 16:50:15 1999  Owen Taylor  <otaylor@redhat.com>
+
+	* gtk/tmpl/gtkrc.sgml: Added information about widget
+	paths and pattern matching.
+
 1999-09-22  Damon Chaplin  <damon@karuna.freeserve.co.uk>
 
 	* gtk/tmpl/*.sgml: ran make templates, to fix problems with structs.
diff --git a/docs/reference/gtk/tmpl/gtkrc.sgml b/docs/reference/gtk/tmpl/gtkrc.sgml
index cfac572a25..17281a0bc5 100644
--- a/docs/reference/gtk/tmpl/gtkrc.sgml
+++ b/docs/reference/gtk/tmpl/gtkrc.sgml
@@ -22,14 +22,12 @@ in the users home directory, and
 (<literal>$localstatedir</literal> defaults to 
 <filename>/usr/local/etc</filename>).
 </para>
-
 <para>
 The set of these <firstterm>default</firstterm> files
 can be retrieved with gtk_rc_get_default_files()
 and modified with gtk_rc_add_default_file() and
 gtk_rc_set_default_files().
 </para>
-
 <para>
 For each default file, in addition to the file itself,
 GTK+ will look for a locale-specific file that will
@@ -43,6 +41,65 @@ first one it finds.
 </para>
 </refsect2>
 
+<refsect2><title>Pathnames and patterns</title>
+<para>
+A resource file defines a number of styles and key bindings and
+attaches them to particular widgets. The attachment is done
+by the <literal>widget</literal>, <literal>widget_class</literal>,
+and <literal>class</literal> declarations. As an example
+of such a statement:
+<programlisting>
+widget "mywindow.*.GtkEntry" style "my-entry-class"
+</programlisting>
+attaches the style <literal>"my-entry-class"</literal>
+to all widgets whose <firstterm>widget class</firstterm>
+matches the <firstterm>pattern</firstterm>
+<literal>"mywindow.*.GtkEntry"</literal>.
+</para>
+<para>
+The patterns here are given in the standard shell glob
+syntax. The <literal>"?"</literal> wildcard matches
+any character, while <literal>"*"</literal> matches
+zero or more of any character. The three types of
+matching are against the widget path, the
+<firstterm>class path</firstterm> and the class
+heirarchy. Both the widget and the class paths consists of a
+<literal>"."</literal> separated list of all the
+parents of the widget and the widget itself from
+outermost to innermost. The difference is that in
+the widget path, the name assigned by
+<function>gtk_widget_set_name()</function> is used
+if present, otherwise the class name of the widget, while
+for the widget path, the class name is always used.
+</para>
+<para>
+So, if you have a <classname>GtkEntry</classname> named
+<literal>"myentry"</literal>, inside of a of a window
+named <literal>"mywindow"</literal>, then the
+widget path is:
+<programlisting>
+"mwindow.GtkHBox.myentry"
+</programlisting>
+while the class path is:
+<programlisting>
+"GtkWindow.GtkHBox.GtkEntry"
+</programlisting>
+</para>
+<para>
+Matching against class is a little different. The pattern
+match is done against all class names in the widgets
+class heirarchy (not the layout heirarchy) in sequence, so the
+pattern:
+<programlisting>
+class "GtkButton" style "my-style"
+</programlisting>
+will match not just <classname>GtkButton</classname> widgets,
+but also <classname>GtkToggleButton</classname> and
+<classname>GtkCheckButton</classname> widgets, since
+those classes derive from <classname>GtkButton</classname>.
+</para>
+</refsect2>
+
 <refsect2><title>Toplevel declarations</title>
 <para>
 An RC file is a text file which is composed of a sequence
@@ -106,7 +163,7 @@ The possible toplevel declarations are:
           <replaceable>name</replaceable></literal></term>
     <listitem>
      <para>Specify a style or binding set for a particular
-     group of widgets by matching on the widget path.</para>
+     group of widgets by matching on the widget pathname.</para>
     </listitem>
   </varlistentry>
   <varlistentry>
@@ -115,7 +172,7 @@ The possible toplevel declarations are:
           <replaceable>name</replaceable></literal></term>
     <listitem>
      <para>Specify a style or binding set for a particular
-     group of widgets by matching on the class path.</para>
+     group of widgets by matching on the class pathname.</para>
     </listitem>
   </varlistentry>
 </variablelist>
-- 
2.30.2